EPD_Spec: Extended Position Description Specification

Revised: 1995.11.26

Technical contact: sje@mv.mv.com (Steven J. Edwards)

1: Introduction

EPD is "Extended Position Description".  It is a standard for describing 
chess positions along with an extended set of structured attribute 
values using the ASCII character set.  It is intended for data and 
command interchange among chessplaying programs.  It is also intended 
for the representation of portable opening library repositories and for 
problem test suites.

EPD is an open standard and is freely available for use by both research 
and commercial programs without charge.  The only requirement for use is 
that any proposed extensions be coordinated through the technical 
contact given at the start of this document.

A single EPD record uses one text line of variable length composed of 
four data fields followed by zero or more operations.  A text file 
composed exclusively of EPD data records should have a file name with 
the suffix ".epd".


2: History

EPD was created in 1993 and is based in part on the earlier FEN standard 
(Forsyth-Edwards Notation) for representing chess positions.  Compared 
to FEN, EPD has added extensions for use with opening library 
preparation and also for general data and command interchange among 
advanced chess programs.  EPD was developed by John Stanback and Steven 
Edwards; its first implementation was in Stanback's commercial 
chessplaying program Zarkov and its second implementation was in 
Edwards' research chessplaying program Spector.  So many programs have 
since adopted EPD that no one knows the exact sequence thereafter.

EPD is employed for storing test suites for chessplaying programs and 
for recording the results of programs running these test suites.  
Example test suites are available for researchers via anonymous ftp from 
the chess.onenet.net site in the pub/chess/Tests directory.  The ASCII 
text file pub/chess/Tests/Manifest gives descriptions of the contents of 
the various test suite files.

EPD is used to provide a linkage mechanism between chessplaying programs 
and position database programs to support the automated direction of 
analysis generation.


3: EPD tools and applications

To encourage development of EPD capable applications, a free EPD tool 
kit is available for program authors working with the ANSI C language.  
To further encourage usage of EPD, a number of free applications are 
also available.


3.1: The EPD Kit

Work is currently in progress on developing an EPD Kit.  This tool kit 
is a collection of portable ANSI C source code files that provide 
routines to create and manipulate EPD data for arbitrarily complex 
records.  It is designed to handle all common EPD related tasks so as to 
assist chess program developers with EPD implementation.  A secondary 
goal is to ensure that every implementation of EPD processing have the 
same set of operational semantics.

The EPD Kit will be made freely available to all chess software authors 
without charge and can be used in both research and commercial 
applications.  As with EPD itself, the only requirement for use is that 
any proposed extensions be coordinated through the technical contact 
given at the start of this document.


3.2: Argus, the automated tournament referee

Work is currently in progress on developing Argus, an automated 
tournament referee program for computer chess events.  Argus uses IP 
(Internet Protocol) communications to act as a mediator for multiple 
pairs of chessplaying programs and to provide an interactive interface 
for a human tournament supervisor.  Argus uses the EPD Kit along with 
other routines to perform the following tasks:

1) Starting chessplaying programs (IP clients) with proper 
initialization data;

2) Relaying position/move data (using EPD) from each program to its 
opponent;

3) Providing all chess clock data as part of the relay process;

4) Record all games using PGN (Portable Game Notation) to assist in the 
production of the tournament final report;

5) Record all moves and other transmitted data in log files for later 
analysis;

6) Detect and report time forfeit conditions;

7) Mediate draw offers and responses between each pair of opponents;

8) Recognize and handle game termination conditions due to draws, 
resignations, time forfeits, and checkmates;

9) Allow for chessplaying program restart and game resumption as 
directed by the human supervisor;

10) Allow for a second instance of itself to operate in observer mode to 
be ready to take over in case of primary machine failure;

11) Support display of games in progress for the benefit of the human 
supervisor and for the general viewing audience.

In its usual configuration, Argus runs on an IP network that connects it 
with all of the participating machines.  It acts like a Unix style 
server using TCP/IP; the chessplaying programs connect to Argus as 
TCP/IP clients.  Unlike a typical Unix style server, it runs in the 
foreground instead of the background when operated by a human 
supervisor.

One variant mode of operation allows for Argus to be started by the host 
system and run in the background.  This use is intended for events where 
human supervision is not required.  Any operating information usually 
provided manually may instead be supplied by configuration files.

Another variant mode of operation allows for Argus to mediate 
communication between a single pair of chessplaying programs using 
regular (unstructured) bidirectional asynchronous serial communication 
instead of IP.  While less reliable than IP operation, unstructured 
serial communication can be used on common inexpensive hardware 
platforms that lack IP support.  An example would be to use common PC 
machines with each chessplaying program running on a separate machine 
and a third machine running Argus in serial mode.  Each of the two 
machines with chessplaying programs connect to the Argus machine via a 
null modem cable.  Note that the Argus machine needs two free serial 
ports while each of the chessplaying machines needs only a single free 
serial port.
The Argus program will be made freely available to all chess software 
authors without charge and can be used in both research and commercial 
applications.  As with EPD itself, the only requirement for use is that 
any proposed extensions be coordinated through the technical contact 
given at the start of this document.


3.3: Gastric, an EPD based report generator

Work is in progress on Gastric, an application that reads EPD files and 
produces statistical reports.  The main use of Gastric is to assist in 
the process of benchmarking chessplaying program performance on EPD test 
suites.  The resulting reports contain summaries of raw performance, 
identification of solved/missed problems, distribution information for 
node count, time consumption, and other items.  Advanced functions of 
Gastric may be used to produce comparative analysis of different 
programs or different versions of the same program.  Some work is also 
planned to allow Gastric output to be used as feedback into 
self-adjusting chessplaying programs.

The Gastric program will be made freely available to all chess software 
authors without charge and can be used in both research and commercial 
applications.  As with EPD itself, the only requirement for use is that 
any proposed extensions be coordinated through the technical contact 
given at the start of this document.


4: The four EPD data fields

Each EPD record contains four data filed that describe the current 
position.  From left to right starting at the beginning of the record, 
these are the piece placement, the active color, the castling 
availability, and the en passant target square of a position.  These can 
all fit on a single text line in an easily read format.  The length of 
an EPD position description varies somewhat according to the position 
and any associated operations. In some cases, the description could be 
eighty or more characters in length and so may not fit conveniently on 
some displays.  However, most EPD records pass among programs only and 
so are not usually seen by program users.

Note: due to the likelihood of future expansion of EPD, implementors are 
encouraged to have their programs handle EPD text lines of up to 4096 
characters long including the traditional ASCII NUL character as a 
terminator.  This is an increase from the earlier suggestion of a 
maximum length of 1024 characters.  Depending on the host operating 
system, the external representation of EPD records will include one or 
more bytes to indicate the end of a line.  These do not count against 
the length limit as the internal representation of an EPD text record is 
stripped of end of line bytes and instead is terminated by the 
traditional ASCII NUL character.

Each of the four EPD data fields are composed only of non-blank printing 
ASCII characters.  Adjacent data fields are separated by a single ASCII 
space character.


4.1: Piece placement data

The first field represents the placement of the pieces on the board.  
The board contents are specified starting with the eighth rank and 
ending with the first rank.  For each rank, the squares are specified 
from file a to file h.  White pieces are identified by uppercase SAN 
(Standard Algebraic Notation) piece letters ("PNBRQK") and black pieces 
are identified by lowercase SAN piece letters ("pnbrqk").  Empty squares 
are represented by the digits one through eight; the digit used 
represents the count of contiguous empty squares along a rank.  The 
contents of all eight squares on each rank must be specified; therefore, 
the count of piece letters plus the sum of the vacant square counts must 
always equal eight.  The solidus character "/" (forward slash) is used 
to separate data of adjacent ranks.  There is no leading or trailing 
solidus in the piece placement data; hence there are exactly seven of 
solidus characters in the placement field.

The piece placement data for the starting array is:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR


4.2: Active color

The second field represents the active color.  A lower case "w" is used 
if White is to move; a lower case "b" is used if Black is the active 
player.

The piece placement and active color data for the starting array is:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w


4.3: Castling availability

The third field represents castling availability.  This indicates 
potential future castling that may or may not be possible at the moment 
due to blocking pieces or enemy attacks.  If there is no castling 
availability for either side, the single character symbol "-" is used.  
Otherwise, a combination of from one to four characters are present.  If 
White has kingside castling availability, the uppercase letter "K" 
appears.  If White has queenside castling availability, the uppercase 
letter "Q" appears.  If Black has kingside castling availability, the 
lowercase letter "k" appears.  If Black has queenside castling 
availability, then the lowercase letter "q" appears.  Those letters 
which appear will be ordered first uppercase before lowercase and second 
kingside before queenside.  There is no white space between the letters.

The piece placement, active color, and castling availability data for 
the starting array is:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq


4.4: En passant target square

The fourth field is the en passant target square.  If there is no en 
passant target square then the single character symbol "-" appears.  If 
there is an en passant target square then is represented by a lowercase 
file character (one of "abcdefgh") immediately followed by a rank digit.  
Obviously, the rank digit will be "3" following a white pawn double 
advance (Black is the active color) or else be the digit "6" after a 
black pawn double advance (White being the active color).

An en passant target square is given if and only if the last move was a 
pawn advance of two squares.  Therefore, an en passant target square 
field may have a square name even if there is no pawn of the opposing 
side that may immediately execute the en passant capture.

The piece placement, active color, castling availability, and en passant 
target square data for the starting array is:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -


5: Operations

An EPD operation is composed of an opcode followed by zero or more 
operands and is concluded by a semicolon.

Multiple operations are separated by a single space character.  If there 
is at least one operation present in an EPD line, it is separated from 
the last (fourth) data field by a single space character.


5.1: General format of opcodes and operands

An opcode is an identifier that starts with a letter character and may 
be followed by up to fourteen more characters.  Each additional 
character may be a letter or a digit or the underscore character.  
Traditionally, no uppercase letters are used in opcode names that are to 
be used by more than one program.


An operand is either a set of contiguous non-white space printing 
characters or a string.  A string is a set of contiguous printing 
characters delimited by a quote (ASCII code: 34 decimal, 0x22 
hexadecimal) character at each end.  A string value must have less than 
256 bytes of data.  This count does not include the traditional ASCII 
NUL character terminator.

If at least one operand is present in an operation, there is a single 
space between the opcode and the first operand.  If more than one 
operand is present in an operation, there is a single blank character 
between every two adjacent operands.  If there are no operands, a 
semicolon character is appended to the opcode to mark the end of the 
operation.  If any operands appear, the last operand has an appended 
semicolon that marks the end of the operation.

Any given opcode appears at most once per EPD record.  Multiple 
operations in a single EPD record should appear in ASCII order of their 
opcode names (mnemonics).  However, a program reading EPD records may 
allow for operations not in ASCII order by opcode mnemonics; the 
semantics are the same in either case.

Some opcodes that allow for more than one operand may have special 
ordering requirements for the operands.  For example, the "pv" 
(predicted variation) opcode requires its operands (moves) to appear in 
the order in which they would be played.  Most other opcodes that allow 
for more than one operand should have operands appearing in ASCII order.  
An example of the latter set is the "bm" (best move[s]) opcode; its 
operands are moves that are all immediately playable from the current 
position.


5.2: Operand basetypes

Operand values are represented using a variety of basetypes.


5.2.1:  Identifier basetype

Some opcodes require one of more operands that are identifiers.  An 
identifier is an unquoted sequence of one to fifteen characters.  The 
characters are selected from the upper and lower case letters, the ten 
digits, and the underscore character.  Most identifiers that may appear 
in EPD are taken from predefined sets as explained in the sections 
covering opcode semantics.

Identifiers are most often used to select one value from a list of 
possible values for a general attribute.  They are also used to 
represent PGN tag attributes.


5.2.2:  Chess move basetype

Some opcodes require one or more operands that are chess moves.  These 
moves should be represented using SAN (Standard Algebraic Notation).  If 
a different representation is used, there is no guarantee that the EPD 
will be read correctly during subsequent processing.  In particular, EDN 
(English Descriptive Notation), CCN (Computer Coordinate Notation), and 
LAN (Long Algebraic Notation) are explicitly not supported.

Chess moves are used most often in single operand operations to select 
one move from the available moves.  They are also used in multiple 
operand operations to define a set of moves (all taken from available 
moves) and in multiple operand operations to express a sequence of moves 
(taken from moves available at each point in a forward sequence of 
play).

Note that some chess moves also qualify as identifiers.  However, the 
semantics of a particular opcode dictate the exact basetype 
interpretation of its operands, so there is no ambiguity.


5.2.3:  Integer basetype

Some opcodes require one or more operands that are integers.  Some 
opcodes may require that an integer operand must be within a given 
range; the details are described in the opcode list given below.  A 
negative integer is formed with a hyphen (minus sign) preceding the 
integer digit sequence.  An optional plus sign may be used for 
indicating a non-negative value, but such use is not required and is 
discouraged.  Support for integers in the range -2147483648 to 
2147483647 (32 bit two's complement signed extrema) is required.

Integers are used to represent centipawn scores and also for various 
counts, limits, and totals.


5.2.4:  Floating basetype

Some opcodes require one or more operands that are floating point 
numbers.  Some opcodes may require that a floating point operand must be 
within a given range; the details are described in the opcode list given 
below.  A floating point operand is constructed from an optional sign 
character ("+" or "-"), a digit sequence (with at least one digit), a 
radix point (always "."), and a final digit sequence (with at least one 
digit).  There is currently no provision for scientific representation 
of numeric values.

The floating basetype in not in current use.


5.2.5:  Date basetype

Some opcodes require one or more operands that represent dates.  These 
are given in a special date format composed of ten characters.  The 
first four characters are digits that give the year (0001-9999), the 
fifth character is a period, the sixth and seventh characters are digits 
that give the month number (01-12), the eighth character is a period, 
and the ninth and tenth characters are digits that give the day number 
in the month (01-31).

The date basetype is used to specify date values in timestamps.


5.2.6:  Time of day basetype

Some opcodes require one or more operands that represent a time of day.  
These are given in a special time of day format composed of eight 
characters.  The first two characters are digits that give the hour 
(00-23), the third character is a colon, the fourth and fifth characters 
are digits that give the minute (00-59), the sixth character is a colon, 
and the seventh and eighth characters are digits that give the second 
(00-59).

The time of day basetype is used to specify time of day values in 
timestamps.


5.2.7:  Clock basetype

Some opcodes require one or more operands that represent a total amount 
of time as would be measured by a traditional digital clock.  These are 
given in a special clock format composed of 12 characters.  The first 
three characters are digits giving a count of days (000-999), the fourth 
character is a colon, the fifth and sixth characters are digits giving a 
count of hours (00-23), the seventh character is a colon, the eighth and 
ninth characters are digits giving a count of minutes (00-59), the tenth 
character is a colon, and the eleventh and twelfth characters are digits 
giving a count of seconds (00-59).

The clock basetype is used to specify clock values for chess clock 
information.  It is not used to measure time consumption for a search; 
an integer count of seconds is used instead.


5.3: Opcode mnemonics

An opcode mnemonic used for archival storage and for interprogram 
communication starts with a lower case letter and is composed of only 
lower case letters, digits, and the underscore character (i.e., no upper 
case letters).  Mnemonics are all at least two characters long.

Opcode mnemonics used only by a single program or an experimental suite 
of programs should start with an upper case letter.  This is so they may 
be easily distinguished should they be inadvertently be encountered by 
other programs.  When a such a "private" opcode be demonstrated to be 
widely useful, it should be brought into the official list (appearing 
below) in a lower case form.

If a given program does not recognize a particular opcode, that 
operation is simply ignored; it is not signaled as an error.


6: Opcode list

The opcodes are listed here in ASCII order of their mnemonics.  
Suggestions for new opcodes should be sent to the technical contact 
listed near the start of this document.


6.1: Opcode "acn": analysis count: nodes

The opcode "acn" takes a single non-negative integer operand.  It is 
used to represent the number of nodes examined in an analysis or search.  
Note that the value may be quite large for some extended searches and so 
use of a long (four byte) representation is suggested.


6.2: Opcode "acs": analysis count: seconds

The opcode "acs" takes a single non-negative integer operand.  It is 
used to represent the number of seconds used for an analysis or search.  
Note that the value may be quite large for some extended searches and so 
use of a long (four byte) representation is suggested.  Also note that 
the special clock format is not used for this operand.  Some systems can 
distinguish between elapsed time and processor time; in such cases, the 
processor time should be used as its value is usually more indicative of 
search effort than wall clock time.


6.3: Opcode "am": avoid move(s)

The opcode "am" indicates a set of zero or more moves, all immediately 
playable from the current position, that are to be avoided as a search 
result.  Each operand is a SAN move; they appear in ASCII order.


6.4: Opcode "bm": best move(s)

The opcode "bm" indicates a set of zero or more moves, all immediately 
playable from the current position, that are judged to the best 
available by the EPD writer and so each is allowable as a search result.  
Each operand is a SAN move; they appear in ASCII order.


6.5: Opcode "c0": comment (primary, also "c1" though "c9")

The opcode "c0" (lower case letter "c", digit character zero) indicates 
a top level comment that applies to the given position.  It is the first 
of ten ranked comments, each of which has a mnemonic formed from the 
lower case letter "c" followed by a single decimal digit.  Each of these 
opcodes takes either a single string operand or no operand at all.

This ten member comment family of opcodes is intended for use as 
descriptive commentary for a complete game or game fragment.  The usual 
processing of these opcodes are as follows:

1) At the beginning of a game (or game fragment), a move sequence 
scanning program initializes each element of its set of ten comment 
string registers to be null.

2) As the EPD record for each position in the game is processed, the 
comment operations are interpreted from left to right.  (Actually, all 
operations in an EPD record are interpreted from left to right.)  
Because operations appear in ASCII order according to their opcode 
mnemonics, opcode "c0" (if present) will be handled prior to all other 
opcodes, then opcode "c1" (if present), and so forth until opcode "c9" 
(if present).

3) The processing of opcode "cN" (0 <= N <= 9) involves two steps.  
First, all comment string registers with an index equal to or greater 
than N are set to null.  (This is the set "cN" though "c9".)  Second, 
and only if a string operand is present, the value of the corresponding 
comment string register is set equal to the string operand.


6.6: Opcode "cc": chess clock values

The opcode "cc" is used to indicate the amount of time used for each 
side at the time of the writing of the opcode to the EPD record.  This 
opcode always takes two values.  Both values are in clock format.  The 
first is the amount of time consumed by White and the second is the 
amount of time consumed by Black.  Note that these values are not simple 
integers.  Also, there is no provision for recording at a resolution of 
less than one second.

This opcode is most commonly used by a mediation program as a source of 
impartial time information for a pair of opposing players.


6.7: Opcode "ce": centipawn evaluation

The opcode "ce" indicates the evaluation of the indicated position in 
centipawn units.  It takes a single operand, an optionally signed 
integer that gives an evaluation of the position from the viewpoint of 
the active player; i.e., the player with the move.  Positive values 
indicate a position favorable to the moving player while negative values 
indicate a position favorable to the passive player; i.e., the player 
without the move.  A centipawn evaluation value close to zero indicates 
a neutral positional evaluation.

Values are restricted to integers that are equal to or greater than 
-32768 and 
are less than or equal to 32766.

A value greater than 32000 indicates the availability of a forced mate 
to the active player.  The number of plies until mate is given by 
subtracting the evaluation from the value 32767.  Thus, a winning mate 
in N fullmoves is a mate in ((2 * N) - 1) halfmoves (or ply) and has a 
corresponding centipawn evaluation of (32767 - ((2 * N) - 1)).  For 
example, a mate on the move (mate in one) has a centipawn evaluation of 
32766 while a mate in five has a centipawn evaluation of 32758.

A value less than -32000 indicates the availability of a forced mate to 
the passive player.  The number of plies until mate is given by 
subtracting the evaluation from the value -32767 and then negating the 
result.  Thus, a losing mate in N fullmoves is a mate in (2 * N) 
halfmoves (or ply) and has a corresponding centipawn evaluation of 
(-32767 + (2 * N)).  For example, a mate after the move (losing mate in 
one) has a centipawn evaluation of -32765 while a losing mate in five 
has a centipawn evaluation of -32757.

A value of -32767 indicates that the side to move is checkmated.  A 
value of -32768 indicates an illegal position.  A stalemate position has 
a centipawn evaluation of zero as does a position drawn due to 
insufficient mating material.  Any other position known to be a certain 
forced draw also has a centipawn evaluation of zero.


6.8: Opcode "dm": direct mate fullmove count

The "dm" opcode is used to indicate the number of fullmoves until 
checkmate is to be delivered by the active color for the indicated 
position.  It always takes a single operand which is a positive integer 
giving the fullmove count.  For example, a position known to be a "mate 
in three" would have an operation of "dm 3;" to indicate this.

This opcode is intended for use with problem sets composed of positions 
requiring direct mate answers as solutions.


6.9: Opcode "draw_accept": accept a draw offer

The opcode "draw_accept" is used to indicate that a draw offer made 
after the move that lead to the indicated position is accepted by the 
active player.  This opcode takes no operands.

The "draw_accept" opcode should not appear on the same EPD record as a 
"draw_reject" opcode.


6.10: Opcode "draw_claim": claim a draw

The opcode "draw_claim" is used to indicate claim by the active player 
that a draw exists.  The draw is claimed because of a third time 
repetition or because of the fifty move rule or because of insufficient 
mating material.  A supplied move (see the opcode "sm") is also required 
to appear as part of the same EPD record.  The "draw_claim" opcode takes 
no operands.

The "draw_claim" opcode should not appear on the same EPD record as a 
"draw_offer" opcode.


6.11: Opcode "draw_offer": offer a draw 

The opcode "draw_offer" is used to indicate that a draw is offered by 
the active player.  A supplied move (see the opcode "sm") is also 
required to appear as part of the same EPD record; this move is 
considered played from the indicated position.  The "draw_offer" opcode 
takes no operands.

The "draw_offer" opcode should not appear on the same EPD record as a 
"draw_claim" opcode.


6.12: Opcode "draw_reject": reject a draw offer

The opcode "draw_reject" is used to indicate that a draw offer made 
after the move that lead to the indicated position is rejected by the 
active player.  This opcode takes no operands.

The "draw_reject" opcode should not appear on the same EPD record as a 
"draw_accept" opcode.


6.13: Opcode "eco": _Encyclopedia of Chess Openings_ opening code

The opcode "eco" is used to associate an opening designation from the 
_Encyclopedia of Chess Openings_ taxonomy with the indicated position.  
The opcode takes either a single string operand (the ECO opening name) 
or no operand at all.  If an operand is present, its value is associated 
with an "ECO" string register of the scanning program.  If there is no 
operand, the ECO string register of the scanning program is set to null.

The usage is similar to that of the "ECO" tag pair of the PGN standard.


6.14: Opcode "fmvn": fullmove number

The opcode "fmvn" represents the fullmove number associated with the 
position.  It always takes a single operand that is the positive integer 
value of the move number.  The value of the fullmove number for the 
starting array is one.

This opcode is used to explicitly represent the fullmove number in EPD 
that is present by default in FEN as the sixth field.  Fullmove number 
information is usually omitted from EPD because it does not affect move 
generation (commonly needed for EPD-using tasks) but it does affect game 
notation (commonly needed for FEN-using tasks).  Because of the desire 
for space optimization for large EPD files, fullmove numbers were 
dropped from EPD's parent FEN.  The halfmove clock information was 
similarly dropped.


6.15: Opcode "hmvc": halfmove clock

The opcode "hmvc" represents the halfmove clock associated with the 
position.  The halfmove clock of a position is equal to the number of 
plies since the last pawn move or capture.  This information is used to 
implement the fifty move draw rule.  It always takes a single operand 
that is the non-negative integer value of the halfmove clock.  The value 
of the halfmove clock for the starting array is zero.

This opcode is used to explicitly represent the halfmove clock in EPD 
that is present by default in FEN as the fifth field.  Halfmove clock 
information is usually omitted from EPD because it does not affect move 
generation (commonly needed for EPD-using tasks) but it does affect game 
termination issues (commonly needed for FEN-using tasks).  Because of 
the desire for space optimization for large EPD files, halfmove clock 
values were dropped from EPD's parent FEN.  The fullmove number 
information was similarly dropped.


6.16: Opcode "id": position identification

The opcode "id" is used to provide a simple identification label for the 
indicated position.  It takes a single string operand.

This opcode is intended for use with test suites used for measuring 
chessplaying program strength.  An example "id" operand for the seven 
hundred fifty seventh position of the one thousand one problems in 
Reinfeld's _1001 Winning Chess Sacrifices and Combinations_ would be 
"WCSAC.0757" while the fifteenth position in the twenty four problem 
Bratko-Kopec test suite would have an "id" operand of "BK.15".


6.17: Opcode "nic": _New In Chess_ opening code

The opcode "nic" is used to associate an opening designation from the 
_New In Chess_ taxonomy with the indicated position.  The opcode takes 
either a single string operand (the NIC code for the opening) or no 
operand at all.  If an operand is present, its value is associated with 
an "NIC" string register of the scanning program.  If there is no 
operand, the NIC string register of the scanning program is set to null.

The usage is similar to that of the "NIC" tag pair of the PGN standard.


6.18: Opcode "noop": no operation

The "noop" opcode is used to indicate no operation.  It takes zero or 
more operands, each of which may be of any type.  The operation involves 
no processing.  It is intended for use by developers for program testing 
purposes.


6.19: Opcode "pm": predicted move

The "pm" opcode is used to provide a single predicted move for the 
indicated position.  It has exactly one operand, a move playable from 
the position.  This move is judged by the EPD writer to represent the 
best move available to the active player.

If a non-empty "pv" (predicted variation) line of play is also present 
in the same EPD record, the first move of the predicted variation is the 
same as the predicted move.

The "pm" opcode is intended for use as a general "display hint" 
mechanism.


6.20: Opcode "ptp": PGN tag pair

The "ptp" opcode is used to record a PGN tag pair.  It always takes an 
even number of operands.  For each pair of operands (from left to 
right), the first operand in the pair is always an identifier and is 
interpreted as the name of a PGN tag; the second operand in the pair is 
always a string and is the value associated with the tag given by the 
first operand.

Any given PGN tag name should only appear once as a tag identifier 
operand in a "ptp" operation.


6.21: Opcode "pv": predicted variation

The "pv" opcode is used to provide a predicted variation for the 
indicated position.  It has zero or more operands which represent a 
sequence of moves playable from the position.  This sequence is judged 
by the EPD writer to represent the best play available.

If a "pm" (predicted move) operation is also present in the same EPD 
record, the predicted move is the same as the first move of the 
predicted variation.


6.22: Opcode "rc": repetition count

The "rc" opcode is used to indicate the number of occurrences of the 
indicated position.  It takes a single, positive integer operand.  Any 
position, including the initial starting position, is considered to have 
an "rc" value of at least one.  A value of three indicates a candidate 
for a draw claim by the position repetition rule.


6.23: Opcode "refcom": referee command

The "refcom" opcode is used to represent a command from a referee 
program to a client program during automated competition.  It takes a 
single identifier operand which is to be interpreted as a command by the 
receiving program.  Note that as the operand is an identifier and not a 
string value, it is not enclosed in quote characters.

There are seven available operand values: conclude, disconnect, execute, 
fault, inform, reset, and respond.

Further details of "refcom" usage are given in the section on referee 
semantics later in this document.


6.24: Opcode "refreq": referee request

The "refreq" opcode is used to represent a request from a client program 
to the referee program during automated competition.  It takes a single 
identifier operand which is to be interpreted as a request to the 
referee from a client program.  Note that as the operand is an 
identifier and not a string value, it is not enclosed in quote 
characters.

There are four available operand values: fault, reply, sign_off, and 
sign_on.

Further details of "refreq" usage are given in the section on referee 
semantics later in this document.


6.25: Opcode "resign": game resignation

The opcode "resign" is used to indicate that the active player has 
resigned the game.  This opcode takes no operands.

The "resign" opcode should not appear on the same EPD record with any of 
the following opcodes: "draw_accept", "draw_claim", "draw_decline', and 
"draw_offer".


6.26: Opcode "sm": supplied move

The "sm" opcode is used to provide a single supplied move for the 
indicated position.  It has exactly one operand, a move playable from 
the position.  This move is the move to be played from the position.

If a "sv" (supplied variation) operation is present on the same record 
and has at least one operand, then its first operand must match the 
single operand of the "sm" opcode.

The "sm" opcode is intended for use to communicate the most recent 
played move in an active game.  It is used to communicate moves between 
programs in automatic play via a network.  This includes correspondence 
play using e-mail and also programs acting as network front ends to 
human players.


6.27: Opcode "sv": supplied variation

The "sv" opcode is used to provide zero or more supplied moves for the 
indicated position.  The operands are a move sequence playable from the 
position.

If an "sm" (supplied move) operation is also present on the same record 
and the "sv" operation has at least one operand, then the "sm" operand 
must match the first operand of the "sv" operation.


6.28: Opcode "tcgs": telecommunication: game selector

The "tcgs" opcode is one of the telecommunication family of opcodes used 
for games conducted via e-mail and similar means.  This opcode takes a 
single operand that is a positive integer.  It is used to select among 
various games in progress between the same sender and receiver.

Details of e-mail implementation await further development.


6.29: Opcode "tcri": telecommunication: receiver identification

The "tcri" opcode is one of the telecommunication family of opcodes used 
for games conducted via e-mail and similar means.  This opcode takes two 
order dependent string operands.  The first operand is the e-mail 
address of the receiver of the EPD record.  The second operand is the 
name of the player (program or human) at the address who is the actual 
receiver of the EPD record.

Details of e-mail implementation await further development.


6.30: Opcode "tcsi": telecommunication: sender identification

The "tcsi" opcode is one of the telecommunication family of opcodes used 
for games conducted via e-mail and similar means.  This opcode takes two 
order dependent string operands.  The first operand is the e-mail 
address of the sender of the EPD record.  The second operand is the name 
of the player (program or human) at the address who is the actual sender 
of the EPD record.

Details of e-mail implementation await further development.


6.31: Opcode "ts": timestamp

The "ts" opcode is used to record a timestamp value.  It takes two 
operands.  The first operand is in date format and the second operand is 
in time of day format. The interpretation of the combined operand values 
gives the time of the last modification of the EPD record.  The 
timestamp is interpreted to be in UTC (Universal Coordinated Time, 
formerly known as GMT).


6.32: Opcode "v0": variation name (primary, also "v1" though "v9")

The opcode "v0" (lower case letter "v", digit character zero) indicates 
a top level variation name that applies to the given position.  It is 
the first of ten ranked variation names, each of which has a mnemonic 
formed from the lower case letter "v" followed by a single decimal 
digit.  Each of these opcodes takes either a single string operand or no 
operand at all.

This ten member variation name family of opcodes is intended for use as 
traditional variation names for a complete game or game fragment.  The 
usual processing of these opcodes are as follows:

1) At the beginning of a game (or game fragment), a move sequence 
scanning program initializes each element of its set of ten variation 
name string registers to be null.

2) As the EPD record for each position in the game is processed, the 
variation name operations are interpreted from left to right.  
(Actually, all operations in an EPD record are interpreted from left to 
right.)  Because operations appear in ASCII order according to their 
opcode mnemonics, opcode "v0" (if present) will be handled prior to all 
other opcodes, then opcode "v1" (if present), and so forth until opcode 
"v9" (if present).

3) The processing of opcode "vN" (0 <= N <= 9) involves two steps.  
First, all variation name string registers with an index equal to or 
greater than N are set to null.  (This is the set "vN" though "v9".)  
Second, and only if a string operand is present, the value of the 
corresponding variation name string register is set equal to the string 
operand.


7: EPD processing verbs

An EPD processing verb is a command to an EPD capable program used to 
direct processing of one or more EPD files.  Standardization of verb 
semantics among EPD capable programs is important to helping reduce 
confusion among program users and to better insure overall 
interoperatibilty.

Each EPD processing verb that requires the reading of EPD records has a 
specific set of required opcodes that must be on each input record.  
Each EPD processing verb that requires the writing of EPD records has a 
specific set of required opcodes that must be on each output record.  
Some EPD processing verbs imply both reading and writing EPD records; 
these will have requirements for both input and output opcode sets.

The names of the EPD processing verbs in this section are for use for 
specification purposes only.  Program authors are free to select 
different names as appropriate for the needs of a program's user 
interface.


7.1: EPD verb: pfdn (process file: data normalization)

The "pfdn" (process file: data normalization) verb reads an EPD input 
file and produces a normalized copy of the data on as the EPD output 
file.  The output file retains the record ordering of the input file.  
The noramlization is used to produce a canonical representation of the 
EPD.  The input records are also checked for legality.  There is no 
minimum set of operations requires on the input records.  For each input 
record, all of the operations present are reproduced in the 
corresponding output record.

The normalization of each EPD record consists of the following actions:

1) Any leading whitespace characters are removed.

2) Any trailing whitespace characters are removed.

3) Any unneeded whitespace characters used as data separators are 
removed; a single blank is used to separate adjacent fields, adjacent 
operations, and adjacent operands.  Also, a single blank character is 
used to separate the fourth position data field (the en passant target 
square indication) from the first operation (if present).

4) Operations are reordered in increasing ASCII order by opcode 
mnemonic.

5) Operands for each opcode that does not require a special order of 
interpretation are reordered in increasing ASCII order by external 
representation.

Data normalization is useful for making a canonical version from data 
produced by programs or other sources that do not completely conform to 
the lexigraphical and ordering rules of the EPD standard.  It also helps 
when comparing two EPD files from different sources on a line by line 
basis; the non-semantic differences are removed so that different text 
lines indicate true semantic difference.


7.2: EPD verb: pfga (process file: general analysis)

The "pfga" (process file: general analysis) verb is used to instruct a 
chessplaying program to perform an analysis for each EPD input record 
and produce an EPD output file containing this analysis.  The output 
file retains the record ordering of the input file.  The current 
position given by each input record is not changed; it is copied to the 
output.

Each input EPD record receives the same analysis effort.  The level of 
effort is indicated as a command (separate from EPD) to the analysis 
program prior to the start of the EPD processing.  Usually, the level is 
given as a time limit or depth limit per each position.  The limit can 
be either a hard limit or a soft limit.  A hard limit represents an 
absolute maximum effort per position, while a soft limit allows the 
program to spend more or less effort per position.  The hard limit 
interpretation is preferred for comparing programs.  The soft limit 
interpretation is used to help test time allocation strategy where a 
program can choose to take more or less time depending on the complexity 
of a position.

Each EPD output record is a copy of the corresponding EPD input record 
with new analysis added as a result of the verb processing.

There is no minimum set of operations required for the EPD input 
records.

Each output EPD record must contain:

1) A "pv" (predicted variation) operation.  The operands of this form a 
sequence of chess moves to be played from the given position.  The 
length of this may vary from record to record due to the level of 
anaylsis effort and the complexity of each position. However, unless the 
current position represents a checkmate or stalemate for the side to 
move, the pv operation must include at least one move.  If the current 
position represents a checkmate or stalemate for the side to move, then 
the pv operation still appears, but has no operands.

2) A "ce" (centipawn evaluation) operation.  The value of its operand is 
the value in hundredths of a pawn of the current position.  Note that 
the evaluation is assigned to the position before the predicted move (or 
any other move) is made.  Thus, a positive centipawn score indicates an 
advantage for the side to move in the current position while a negative 
score indicates a disadvantage for the side to move.

Each output EPD record may also contain:

1) A "pm" (predicted move) operation, unless the current position 
represents a checkmate or stalemate for the side to move.  (If the side 
to move has no moves, then the "pm" operation will not appear.)  The 
single operand of the "pm" opcode must be the same as the first operand 
of the "pv" sequence.

2) A "sm" (supplied move) operation, unless the current position 
represents a checkmate or stalemate for the side to move.  (If the side 
to move has no moves, then the "sm" operation will not appear.)  The 
single operand of the "sm" opcode must be the same as the first operand 
of the "pv" sequence.

3) An "acn" (analysis count: nodes) operation.  The single operand is 
the number of nodes visited in the analysis search for the position.

4) An "acs" (analysis count: seconds) operation.  The single operand is 
the number of seconds used for the analysis search for the position.


7.3: EPD verb: pfms (process file: mate search)

The "pfms" verb is used to conduct searches for forced checkmating 
sequences.  The length of the forced mate sequence is provided (outside 
of EPD) to the program prior to the beginning of "pfms" processing.  The 
length is specified using a fullmove count.  For example, a fullmove 
mate length of three would instruct the program to search for all mates 
in three.  An analysis program reads and input EPD file and looks for 
forced mates in each position where no forced mate of equal or lesser 
length has been recorded.  The output file retains the record ordering 
of the input file.

The action of the "pfms" command on each record is governed by the 
pre-specified fullmove count and, if present on the record, the value of 
the "dm" (direct mate fullmove count) operand.  A particular record will 
be subject to a search for a forced mate if either:

1) There is no "dm" operation on the input record, or

2) The value of the "dm" operand on the input record is greater than the 
value of the pre-specified fullmove analysis length.

If the analysis program finds a forced mate, it produces two additional 
operations on the corresponding output EPD record:

1) A "dm" operation with an operand equal to the pre-specified fullmove 
mate length.

2) A "pm" operation with the first move of the mating sequence as its 
operand.  If two or more such moves exist, the program selects the first 
one it located to appear as the "pm" operand.

The idea is that a set of positions can be repeatedly scanned by a mate 
finding program with the fullmove analysis depth starting with a value 
of one and being increased by one with each pass.  For any given pass, 
the positions solved by an earlier pass are skipped.

The output EPD records may also contain other (optional) information 
such as "acn", "acs", and "pv" operations.


7.4: EPD verb: pfop (process file: operation purge)

The "pfop" verb is used to purge a particular operation from each of the 
records in an EPD file that contain the operation.  The output file 
retains the record ordering of the input file.  Prior to processing, the 
opcode of the operation to be purged is specified.

The records of the input file are copied to the output file.  If the 
pre-specified operation is present on a record, the operation is removed 
prior to copying the record to the output.


7.5: EPD verb: pfts (process file: target search)

The "pfts" (process file: target search) verb is similar to the "pfga" 
(process file: general analysis) verb in that each position on the EPD 
input file is subject to a general analysis.  The difference is that 
each input record contains a set of target moves and a set of avoidance 
moves.  Either of these two sets, but not both, may be empty.  The set 
of avoidance moves is given by the operands of a "am" opcode (if 
present).  The set of target moves is given by the operands of a "bm" 
opcode (if present).

Prior to processing the target search, the program is given a search 
effort limit such as a limit on the amount of search time or search 
nodes per position.  The "pfts" verb causes each input EPD record to be 
read, subjected to analysis, and then written to output file with the 
predicted move attached with the "pm" opcode.  (No "pm" operation is 
added is the current position is a checkmate or stalemate of the side to 
play.)

The output EPD records may also contain other (optional) information 
such as "acn", "acs", and "pv" operations.


8: EPD referee semantics

Communication between a chessplaying program and a referee program is 
performed by exchanging EPD records.  Each EPD record emitted by a 
chessplaying program to be received by the referee has a "refreq" EPD 
opcode with an operand that describes the request.  Each EPD record 
emitted by a referee to be received by a chessplaying program has a 
"refcom" EPD opcode with an operand that describes the command.

The usual operation sequence in a referee mediated event is as follows:

1) The referee server program is started and the human event supervisor 
provides it with any necessary tournament information including the 
names of the chessplaying programs, the name of the event, and various 
other data.

2) The referee program completes its initialization by performing 
pairing operations as required.

3) Once the server has its initial data, it then opens a socket and 
binds it to the appropriate port.  It then starts listening for input 
from clients.  For a serial implementation, an analogous function is 
performed.

4) The competing chessplaying programs (clients) are started (if not 
already running) and are given the name of the referee host machine 
along with the port number.  For a serial implementation, an analogous 
function is performed.

5) Each client program transmits an EPD record to the referee requesting 
registration.  This causes each client to be signed on to the referee.

6) The referee program replies to each client signing on with an EPD 
record commanding a reset operation to set up for a new game.

7) The referee program sends an EPD record to each client informing each 
client about the values for each of the tag values for the PGN Seven Tag 
Format.

8) For each client on the move, the referee will send an EPD record 
commanding a response.  This causes each receiving client to calculate a 
move.  If there has been a prior move, it along with the position from 
which the move is played is sent.  If there has been no prior move, the 
current position is sent but no move is included.

9) For each client receiving a command to respond, the current position 
indicated by the record is set as the current position in the receiving 
program.  (It should already be the current position in the receiver.)  
If a supplied move was given, it is executed on the current position.  
Finally, the receiving program calculates a move.

10) As each program on the move completes its calculation, it sends a 
reply to the referee which includes the result of the calculation.  The 
position sent back on the reply is the result of applying the move 
received on the referee record to the position on the same received 
record.  If a move was produced as the result of the calculation, it is 
also sent.  (A move will not be produced or sent if the receving client 
was checkmated, or if it was stalemated, of if it resigns, or claims a 
draw due to insufficient material.)

11) As the referee receives a reply from a client, it produces a respond 
command record to the client's opponent.  (This step will be skipped if 
an end of game condition is detected and no further moves need to be 
communicated.)

12) The referee continues with the respond/reply cycle for each pair of 
opponent clients until the game concludes for that pair.

13) For each game conclusion, the referee sends a conclude command to 
each of the clients involved.

14) When a client is to be removed from competition, it sends a sign off 
request.  This eliminates that program from being paired until it 
re-registers with a sign on request.

15) When the referree server is to be removed from network operations, 
it will send a disconnect command to each client that is currently 
signed on to the referee.

8.1: Referee commands (client directives)

The referee communicates the command of interest as the single operand 
of the "refcom" opcode.  The refcom opcode will be on each record sent 
by the referee.  Each possible refcom operand is sent as an identifier 
(and not as a string).

EPD records sent by the referee will include check clock data as 
appropriate.  Whenever a client program receives a record with the "cc" 
(chess clock) opcode, the client should set the values of its internal 
clocks to the values specified by the cc operands.  Note that the clock 
values for both White and Black are present in a cc operation.

All EPD records carry the four data fields describing the current 
position.  In most cases, this position should also be the current 
position of the receiving client.  If the position sent by the referee 
matches the client's current position, then the client can assume that 
all of the game history leading to the current position is valid.  Thus, 
every client keeps track of the game history internally and uses this to 
detect repetition draws and so there is no need for each EPD record to 
contain a complete copy of the game history.

If the position sent by the referee does not match the receiving 
program's current position, then the receiving program must set its 
current position to be the same as the one it received.  Unless an 
explicit game history move sequence is also sent on the same EPD record, 
the receiving program is to assume that the new (different) position 
received has no game history.  In this case the receiving program cannot 
check for repetition of positions prior to the new position as there 
aren't any previous positions in the game.

Each client is expected to maintain its own copy of the halfmove clock 
(plies since last irreversible move; starts at zero for the initial 
position) and the fullmove number (which has a value of one for the 
initial position).  If the referee sends a halfmove clock value or a 
fullmove number which is different from that kept by the program, then 
the receiving program is to treat it as a new position and clear any 
game history.  As noted above, a halfmove clock is sent using the "hmvc" 
opcode and a fullmove number is sent using a "fmvn" opcode.

If a supplied move (always using the "sm" opcode) is sent by the 
referee, the receiving program must execute this move on the current 
position.  This is done after the program's current position is set to 
the position sent by the referee (remember that the two will usually 
match).  The resulting position becomes the new current position.  This 
new current position is used for all further calculations.  The new 
current position is also the position to be sent to the referee if a 
move response is commanded.  When a client program produces a move to be 
played, it uses the sm opcode with its operand being the supplied move.  
The position sent is alwasy the position from which the supplied move is 
to be played.  Thus, the semantics of the current position and the 
supplied move are symmetric with respect to the client and the server.


8.1.1: Referee command: conclude

The "conclude" refcom operand instructs the client to conclude the 
current game in progress.  The position sent is the final position of 
the game.  There is no supplied move sent.  No further EPD records 
concerning the game will be sent by the referee.  The client should 
perform any end of game activity required for its normal operation.  No 
response from the client is made.

To allow for client game conclusion processing time, the referee will 
avoid sending any more EPD records to a client concluding a game for a 
time period set by the human supervisor.  The default delay will be five 
seconds.


8.1.2: Referee command: disconnect

The "disconnect" refcom operand instructs the client that the referee is 
terminating service operations.  The client should close its 
communication channel with the server.  This command is sent at the end 
of an event or whenever the referee is to be brought down for some 
reason.  No further EPD records will be sent until the server is cycled.  
It provides an opportunity for a client to gracefully disconnect from 
network operations with the server.  No supplied move is sent.  The 
position sent is irrelevant.  No response from the client is made.


8.1.3: Referee command: execute

The "execute" refcom operand instructs the client to set up a position.  
If a move is supplied (it usually is), then that move is executed from 
the position.  The sent position will usually be the receiver's current 
position.  This command is used only to play through the initial 
sequence of moves from a game to support a restart capability.  No 
response is made by the receiver.


8.1.4: Referee command: fault

The "fault" refcom operand is used to indicate that the referee has 
detected an unrecoverable fault.  The reciever should signal for human 
intervention to assist with corrective action.  The human supervisor 
will be notified by the referee regarding the nature of the fault.  No 
response is made by the receiver.

A future version of the referee protocol will support some form of 
automated fault recovery.


8.1.5: Referee command: inform

The "inform" refcom operand is used to convey PGN tag pair data to the 
receiver.  The "ptp" opcode will carry the PGN tag data to be set on the 
receiving client.  This command may be sent at any time.  It will 
usually be sent prior to the first move of a game.  It will also be sent 
after the last move of a game to communicate the result of the game via 
the PGN "Result" tag pair.  No response is made by the receiver.

The main purpose for the inform referee command is to be able to 
communcate tag pair data to a client without having to send a move or 
other command.  Note that the ptp opcode may also appear on EPD records 
from the referee that are not inform commands; its operands are 
processed in the same way.

The usual information sent includes the values for the Seven Tag Roster.  
The PGN tag names are "Event", "Site", "Date", "Round", "White", 
"Black", and "Result".

Future versions of the referee will likely send more than just the Seven 
Tag Roster of PGN tag pairs.  One probable addition will be to send the 
"TimeControl" tag pair prior to the start of a game; this will allow a 
receiving program to have its time control parameters set automatically 
rather than manually.


8.1.6: Referee command: reset

The "reset" refcom operand is used to command the receiving client to 
set up for a new game.  Any previous information about a game in 
progress is deleted.  This command will be sent to mark the beginning of 
a game.  It will also be sent if there is a need to abort the game 
currently in progress.  No response is made by the receiver.

To allow for client reset processing time, the referee will avoid 
sending any more EPD records to a resetting client for a time period set 
by the human supervisor.  The default delay will be five seconds.


8.1.7: Referee command: respond

The "respond" refcom operand is used to command the receiving client to 
respond to the move (if any) played by its opponent.  The position to 
use for calculation is the position sent which is modified by a supplied 
move (if present; uses the "sm" opcode).  The client program calculates 
a response and sends it to the referee using the "reply" operand of the 
"refreq" opcode.


8.2: Referee requests (server directives)

The referee communicates the command of interest as the single operand 
of the "refcom" opcode.  The refcom opcode will be on each record sent 
by the referee.  Each possible refcom operand is sent as an identifier 
(and not as a string).


8.2.1: Referee request: fault


The "fault" refreq operand is used to indicate that the client has 
detected an unrecoverable fault.  The receiver should signal for human 
intervention to assist with corrective action.  The human supervisor 
will be notified by the referee regarding the nature of the fault.  No 
response is made by the referee.

A future version of the referee protocol will support some form of 
automated fault recovery.


8.2.2: Referee request: reply

The "reply" refreq operand is used to carry a reply by the client 
program.  Usually, a move (the client's reply) is included as the 
operand of the "sm" opcode.


8.2.3: Referee request: sign_off

The "sign_off" refreq operand is used to indicate that the client 
program is signing off from the referee connection and no further 
operations will be made on the communication channel.  The channel in 
use is then closed by both the referee and the client.

A new connection must be established and a new "sign_on" referee request 
needs to be made for further referee operations with the client.


8.2.4: Referee request: sign_on

The "sign_on" refreq operand is used to indicate that the client program 
is signing on to the referee connection.  This request is required 
before any further operations can be made on the communication channel.  
The channel in use remains open until it is closed by either side.


9: EPD report generation semantics

[TBD]


EPD_Spec: EOF